using System.Collections.Generic;
using System.IO;

namespace NFreeMarker.Template
{
    /**
     * Objects that implement this interface can be used as user-defined directives 
     * (much like macros); you should rather use the newer {@link TemplateDirectiveModel}
     * instead. Altough implementing output filters is more handy with this interface,
     * this interface will be certainly deprecated as superfluous, starting from
     * FreeMarker 2.4. But as far as the template engine is concerned, you can use both
     * equivalently as a user-defined directive.
     *
     * <P>Note that, as of FreeMarker 2.1, <tt>TemplateTransformModel</tt>
     * has changed. This is a more powerful implementation. 
     * There is a quick-and-dirty way to patch any legacy
     * TemplateTransformModel so that it implements the new API.
     * You simply add the following as your implementation 
     * of the getWriter() call:
     * <PRE>
     * 
     *    public Writer getWriter(final Writer out, 
     *                            Map args) 
     *    {
     *       final StringBuffer buf = new StringBuffer();
     *       return new Writer() {
     *           public void write(char cbuf[], int off, int len) {
     *               buf.append(cbuf, off, len);
     *           }
     *
     *           public void flush() throws IOException {
     *               out.flush();
     *           }
     * 
     *           public void close() throws IOException {
     *               StringReader sr = new StringReader(buf.toString());
     *               StringWriter sw = new StringWriter();
     *               transform(sr, sw);
     *               out.write(sw.toString());
     *           }
     *       };
     *   }
     *
     * 
     * </PRE>
     * 
     * @author Attila Szegedi
     * @version $Id: TemplateTransformModel.java,v 1.36 2003/04/11 20:57:32 revusky Exp $
     */

    public interface ITemplateTransformModel : ITemplateModel
    {
        /**
          * Returns a writer that will be used by the engine to feed the
          * transformation input to the transform. Each call to this method
          * must return a new instance of the writer so that the transformation
          * is thread-safe.
          * @param out the character stream to which to write the transformed output
          * @param args the arguments (if any) passed to the transformation as a 
          * map of key/value pairs where the keys are strings and the arguments are
          * TemplateModel instances. This is never null. If you need to convert the
          * template models to POJOs, you can use the utility methods in the 
          * {@link DeepUnwrap} class.
          * @return a writer to which the engine will feed the transformation 
          * input, or null if the transform does not support nested content (body).
          * The returned writer can implement the {@link TransformControl}
          * interface if it needs advanced control over the evaluation of the 
          * transformation body.
          */
        TextWriter GetWriter(TextWriter outStream, IDictionary<string, ITemplateModel> args);
    }
}